home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / dev / gui / js_tools123.lha / js_tools / programmers / autodocs / js_tools.doc
Encoding:
Text File  |  1995-02-27  |  34.7 KB  |  1,090 lines
  1. TABLE OF CONTENTS
  2.  
  3. js_tools.library/JS_LibInfo
  4. js_tools.library/JS_Sort
  5. js_tools.library/LV_AskListViewAttrs
  6. js_tools.library/LV_CreateExtraListViewA
  7. js_tools.library/LV_CreateListViewA
  8. js_tools.library/LV_FreeListView
  9. js_tools.library/LV_FreeListViews
  10. js_tools.library/LV_GetIMsg
  11. js_tools.library/LV_GetListViewAttrsA
  12. js_tools.library/LV_KeyHandler
  13. js_tools.library/LV_RefreshWindow
  14. js_tools.library/LV_ReplyIMsg
  15. js_tools.library/LV_SetListViewAttrsA
  16. js_tools.library/Xtra: listview tag item overview
  17. js_tools.library/JS_LibInfo              js_tools.library/JS_LibInfo
  18.  
  19.    NAME
  20.     JS_LibInfo -- Get some information (strings and numbers) of the
  21.     library
  22.  
  23.    SYNOPSIS
  24.     information = JS_LibInfo(type);
  25.     D0             D1
  26.  
  27.     STRPTR JS_LibInfo ( ULONG type );
  28.  
  29.    FUNCTION
  30.     Get some information (copyright note, version, etc.) of the library
  31.     e.g.  for an info window of a program (would be nice).
  32.     JSINFO_BOX       (STRPTR) - a short text for info windows,
  33.                       it may change!
  34.     JSINFO_VERSION       (STRPTR) - version string of the library,
  35.                       may change in size
  36.     JSINFO_LIBVERSION  (ULONG)  - version
  37.     JSINFO_LIBREVISION (ULONG)  - revision
  38.     JSINFO_DATE       (STRPTR) - date of compilation
  39.  
  40.    INPUTS
  41.     type - type of information
  42.  
  43.    RESULT
  44.     information (D0) - string or simple a ULONG - depents on type
  45.  
  46. js_tools.library/JS_Sort                 js_tools.library/JS_Sort
  47.  
  48.    NAME
  49.     JS_Sort -- sorts a node list with quicksort
  50.  
  51.    SYNOPSIS
  52.     JS_Sort(list, number);
  53.         A0    D0
  54.  
  55.     void JS_Sort ( struct List *list, LONG number );
  56.  
  57.    FUNCTION
  58.     Sorts a node list alphabetically case insensitiv and can handle
  59.     locale characters (e.g.  german umlauts) with locale.library.  If
  60.     number is set to 0 the function will count the number of nodes
  61.     itself.  But if you already know them why take this extra time?
  62.  
  63.    INPUTS
  64.     list - list to sort
  65.  
  66.     number - number of nodes, if set to 0 JS_Sort() will count itself
  67.  
  68. js_tools.library/LV_AskListViewAttrs     js_tools.library/LV_AskListViewAttrs
  69.  
  70.    NAME
  71.     LV_AskListViewAttrs -- a short way for AskTags
  72.  
  73.    SYNOPSIS
  74.     data = LV_AskListViewAttrs(gad, win, tag, data);
  75.     D0               A0    A1   D0   D1
  76.  
  77.     ULONG LV_AskListViewAttrs ( struct Gadget *gad, struct Window *win,
  78.         Tag tag, ULONG data );
  79.  
  80.    FUNCTION
  81.     If you want to get only one parameter from a gadget this is a short
  82.     way to do it.
  83.  
  84.    INPUTS
  85.     gad - Gadget to get information from
  86.  
  87.     win - Window of gadget
  88.  
  89.     tag - AskTag
  90.  
  91.     data - if required some additional parameter
  92.  
  93.    RESULT
  94.     data (D0) - result of AskTag
  95.  
  96.    TAGS
  97.     lv_AskTop (WORD) returns lv_Top in ti_Data field
  98.  
  99.     lv_AskLines (WORD) number of visible lines in ti_Data
  100.  
  101.     lv_AskNumber (WORD) number of lines in current list
  102.  
  103.     lv_AskNode (struct Node*) Selected Node
  104.  
  105.     lv_IsShown (BOOL) is selected item shown ?
  106.  
  107.     lv_IsMarked (BOOL) is (struct Node*) in data marked ?
  108.  
  109.     lv_IsMarkedNr (BOOL) is line in data marked ? Like lv_IsMarked
  110.  
  111.     lv_MarkedCount (WORD) number of marked lines
  112.  
  113.     lv_AskHoriz (LONG) get horizontal position of SuperLV - this is the
  114.         only way to get this information (exept you use
  115.         LV_GetListViewAttrsA() with lv_HorizSelected)
  116.  
  117.     lv_AskHorizMax (LONG) maximal position for lv_AskHoriz, is changed by
  118.         every lv_Lables call
  119.  
  120. js_tools.library/LV_CreateExtraListViewA
  121.  
  122.    NAME
  123.     LV_CreateExtraListViewA -- Creates a new extra listview
  124.     (lvExtraWindow)
  125.  
  126.    SYNOPSIS
  127.     gadget = LV_CreateExtraListViewA(exw, tags);
  128.     D0                 A0   A1
  129.  
  130.     struct Gadget *LV_CreateExtraListViewA ( struct lvExtraWindow *exw,
  131.         struct TagItem *tags );
  132.  
  133.    FUNCTION
  134.     Creates an extra listview gadget.  A ListView will be put in an own
  135.     window.  You may use the return parameter with all js_tools listview
  136.     functions.  It is impossible to add a string gadget with
  137.     lv_ShowSelected.  All results of this listview (selected, etc.) will
  138.     be send to the messageport of the window given in the struct
  139.     lvExtraWindow.    This window has to be opened the hole time the
  140.     lvExtraWindow is open! So if you want to close this window you first
  141.     must close the lvExtraWindows.    The IntuiMessage contains in IAddress
  142.     a pointer to the gadget (as always).  Attention! This is no intuition
  143.     gadget structure! Only the GadgetID and UserData fields have the same
  144.     offset like intuition gadgets! Please look in C includes for struct
  145.     lvExtraWindow.    You must not reply an IntuiMessage of a lvExtraWindow
  146.     after it has been closed (with LV_FreeListView()).
  147.  
  148.    INPUTS
  149.     exw - lvExtraWindow that contains all required data
  150.  
  151.     tags - tagitems
  152.  
  153.    RESULT
  154.     gadget (D0) - gadget pointer to use with other functions, NULL for
  155.         error
  156.  
  157.    EXAMPLE
  158.     /* Handling IDCMP messages (one way): */
  159.     myMSG=LV_GetIMsg(myWin->UserPort);
  160.     if (myMSG) /* maybe we got a NULL pointer! Use this way ALWAYS. */
  161.     {
  162.       if (myMSG->IDCMPWindow==myWin)
  163.       {
  164.          /* this are IDCMP events for our window */
  165.          /* put your code here */
  166.         LV_ReplyIMsg(myMSG);
  167.       }
  168.       else
  169.       {
  170.         /* this are IDCMP events of the lvExtraWindow */
  171.         /* look in IAddress for a struct gadget to find out */
  172.         /* the right lvExtraWindow */
  173.         /* possibel events: */
  174.         /*     IDCMP_CLOSEWINDOW - use LV_FreeListView() to close the */
  175.         /*                 lvExtraWindow */
  176.         /*                 after LV_FreeListView() you must not */
  177.         /*                 use this pointer again, its gone! */
  178.         /*     IDCMP_GADGETUP    - same as normal, look in Code field */
  179.         /*                 for selected item */
  180.         /*     IDCMP_RAWKEY       - pressed key in this window, */
  181.         /*                 do want you want to do with it */
  182.         /*     IDCMP_VANILLAKEY  - do the same as RAWKEY */
  183.         LV_ReplyIMsg(myMSG);
  184.         /* reply message before you close the lvExtraWindow ! */
  185.       }
  186.     }
  187.  
  188.    SEE ALSO
  189.     CreateListViewA()
  190.  
  191.    TAGS
  192.     see LV_CreateListViewA()
  193.  
  194. js_tools.library/LV_CreateListViewA      js_tools.library/LV_CreateListViewA
  195.  
  196.    NAME
  197.     LV_CreateListViewA -- Creates a new listview
  198.  
  199.    SYNOPSIS
  200.     gadget = LV_CreateListViewA(kind, prev, newg, tags);
  201.     D0                D0      A0    A1    A2
  202.  
  203.     struct Gadget *LV_CreateListViewA ( LONG kind, struct Gadget *prev,
  204.         struct NewGadget *newg, struct TagItem *tags );
  205.  
  206.    FUNCTION
  207.     Creates a new listview gadget and adds to the prev gadget list.  The
  208.     fields ng_GadgetText and ng_Flags are currently ignored, set to NULL.
  209.     If you want to add a text above, below, left or right of the listview
  210.     use a gadtools TEXT_KIND gadget (you can use the same left & top edge
  211.     and the same width & height, but the TEXT_KIND gadget should have no
  212.     border and no text inside).  If this function was successfull you get
  213.     a pointer to the listview gadget.  The NewGadget.ng_Height field has
  214.     been changed to the real listview height (which could be smaller).
  215.     This height includes an added string gadget (like gadtools).
  216.  
  217.    INPUTS
  218.     kind - kind of listviews
  219.  
  220.     prev - previous gadget
  221.  
  222.     newg - gadtools NewGadget
  223.  
  224.     tags - tagitems for additional infos
  225.  
  226.    RESULT
  227.     gadget (D0) - gadget pointer to use with other functions, NULL if
  228.         error
  229.  
  230.    NOTE
  231.     Requesters are currently not supported
  232.  
  233.    SEE ALSO
  234.     gadtools/CreateGadgetA()
  235.  
  236.    TAGS
  237.     lv_Labels (struct List*) like GTLV_Labels - Text to show in struct
  238.         List* or MinList*
  239.  
  240.     lv_Disabled (BOOL) like GA_Disabled - disables listview - scrolling
  241.         is still possible so the hook could be started!
  242.  
  243.     lv_ScrollWidth (LONG) like GTLV_ScrollWidth - width of scroller,
  244.         default: 16
  245.  
  246.     lv_ShowSelected (struct Gadget*) like GTLV_ShowSelected - 0 show
  247.         selected or a pointer to a stringgadget to show it there if
  248.         you use multi columns the struct Node->ln_Name field is still
  249.         used!
  250.  
  251.     lv_ReadOnly (BOOL) like GTLV_ReadOnly - ListView is readonly
  252.  
  253.     lv_Spacing (LONG) like LAYOUTA_Spacing - additional free pixel lines
  254.         between each text line (default 0)
  255.  
  256.     lv_Top (LONG) like GTLV_Top - sets first show line - the real top
  257.         line is returned in ti_Data field
  258.  
  259.     lv_Selected (LONG) like GTLV_Selected - sets selected line - the real
  260.         selected line is returned in ti_Data
  261.  
  262.     lv_NewSelected much better select function - selected line is
  263.         automatically shown by as less as possible scrolling the
  264.         listview - the real selected line is returned in ti_Data
  265.  
  266.     lv_SetMark (LONG) mark a line (0-...)
  267.  
  268.     lv_ClearMark (LONG) unmark line (0-...) - use "ask tags" to get
  269.         current state of a line
  270.  
  271.     lv_BlockStart (LONG) mark lines in a block - upper line here
  272.  
  273.     lv_BlockStop (LONG) mark lines in a block - last line here
  274.  
  275.     lv_MarkBlock (BOOL) if TRUE block is marked, if FALSE block is
  276.         unmarked
  277.  
  278.     lv_MarkIsIn (ULONG) mark offset (to struct Node start), BYTE field
  279.         the hole list will be marked/unmarked as set in this offset -
  280.         ==1==TRUE means set mark e.g.  OFFSETOF(struct
  281.         myNode,markfield)
  282.  
  283.     lv_OnlyRead (LONG) number of lines at the end of the list that are
  284.         read only
  285.  
  286.     lv_Colour (LONG) colour of text in the listview - don't use this
  287.         other or you will confuse user
  288.  
  289.     lv_Color (LONG) other name for lv_Colour (first is british english)
  290.  
  291.     lv_NewSelectMode (LONG) set NSM mode for lv_NewSelected:
  292.         NSM_ExtraLine: one line at the listview border is always
  293.                    visible (DEFAULT)
  294.         NSM_Center   : selected is centered
  295.                    (exept at start/end of the list)
  296.         NSM_NoLine   : like good old gadtools ListView
  297.         NSM_FreeLine : like NSM_ExtraLine, but the number of visible
  298.                    lines is set by lv_NewSelectLines tag.
  299.                    If you use this tag it is possible that there
  300.                    are less lines visible this is to minimize
  301.                    scrolling and not confuse the user.
  302.  
  303.     lv_NewSelectLines (LONG) lines in NSM_FreeLines mode
  304.  
  305.     lv_OffIsIn (ULONG) offset to lock byte (see lv_MarkIsIn) If byte is
  306.         ==1 the current node is locked and can't be selected.  The
  307.         field must exist as long as you use the list, if you change
  308.         it use lv_Redraw to update output.  Tag must be used every
  309.         time lv_Lables is used or locking will be turned of.
  310.  
  311.     lv_ElseSelected (LONG) if (New)Selected points to a locked line this
  312.         tag specifies what to do: >=0 -> select next line, <= ->
  313.         select prev line (Default: 0) usefull if you program a
  314.         keyboard interface for a listview
  315.  
  316.     lv_OffColour (LONG) colour of locked text
  317.  
  318.     lv_OffColor (LONG) other name for lv_OffColour
  319.  
  320.     lv_xFrontColour (LONG) text colour of marked text if LISTVIEW2_KIND
  321.         is used
  322.  
  323.     lv_xFrontColor (LONG) other name for lv_xFrontColour
  324.  
  325.     lv_xBackColour (LONG) background colour of marked text if
  326.         LISTVIEW2_KIND is used
  327.  
  328.     lv_xBackColor (LONG) right, other name for lv_xBackColour
  329.  
  330.     lv_Hook (struct Hook*) pointer to Hook.  The Hook will get a struct
  331.         lvData in A2.  Please look in C includes for description of
  332.         struct lvData.
  333.  
  334.     lv_Notick (BOOL) do not send IDCMP_INTUITICKS if they are already
  335.         used by listview (Default: TRUE)
  336.  
  337.     lv_AlwaysMark (BOOL) the default way to mark a line is to press SHIFT
  338.         key while selecting if this tag is TRUE lines are always
  339.         marked - also if SHIFT isn't pressed - lv_MarkOn tag must be
  340.         TRUE, too!
  341.  
  342.     lv_MarkOn (BOOL) turns on mark mode, so the user can mark lines if
  343.         not turned on only the program may mark a line (so SHIFT is
  344.         ignored) - default: FALSE
  345.  
  346.     lv_SuperListView (BOOL) make Super ListView (TRUE) - i.e.  it may
  347.         scroll horizontal - default: FALSE It has some things in
  348.         common with intuitions Super Bitmap Windows.  ATTENTION! This
  349.         kind of listview isn't that fast - so use it only for small
  350.         listviews.  If there is less chip ram it falls back to a
  351.         normal listview! Currently it is impossible to use a Super
  352.         Listview in lvExtraWindows!
  353.  
  354.     lv_ScrollHeight (LONG) Height of horizontal scroller (see
  355.         lv_ScrollWidth), Default: lv_ScrollWidth-(lv_ScrollWidth/3)
  356.  
  357.     lv_HorizSelected (LONG) Horizontal position in pixel (first is 0)
  358.  
  359.     lv_HorizScroll (LONG) pixels to scroll if mouse if moved left or
  360.         right out of the listview (Default: 4).
  361.  
  362.     lv_Private1 (LONG) private tagitem, do not use
  363.  
  364.     lv_ColumnData (struct ColumnData*) pointer to a ColumnData array.
  365.         Listviews may have more than one column.  Each column is
  366.         represented by one struct ColumnData that contains its width,
  367.         where is starts, Text adjustment and an offset to the text in
  368.         each Node (see lv_MarkIsIn).  Field ln_Name of the struct
  369.         Node is not shown so you must add a ColumnData for it, too.
  370.         But it is shown in an added string gadget.  To end the array
  371.         simply add a ColumnData with all fields set to 0 (NULL).  The
  372.         array has to be sorted by size of start - smallest first.
  373.         Please look in C includes for details of struct ColumnData.
  374.  
  375.     lv_FormatText (STRPTR) Text (+0 byte) that will be fit optimal in the
  376.         listview - replacement for lv_Labels.  Column mode will be
  377.         deactivated, this tag should be used in readonly listviews.
  378.         You can start a new paragraph with ASCII#10 (Linefeed, \n).
  379.         lvExtraWindow update text form every time it is resized.  In
  380.         lvExtraWindow the text string must be available the hole time
  381.         it is applied to the listview!! In normal listviews the text
  382.         string has to be available until LV_RefreshWindow() is called
  383.         because graphics/TextFit() needs a RastPort which is not
  384.         before this call set.  This may change.
  385.  
  386.     lv_AfterHook (struct Hook*) pointer to Hook.  The hook will get a
  387.         struct lvData in A2.  This hook will be started after a line
  388.         has been print out.  Please look in C includes for
  389.         description of struct lvData.
  390.  
  391. js_tools.library/LV_FreeListView         js_tools.library/LV_FreeListView
  392.  
  393.    NAME
  394.     LV_FreeListView -- frees a listview
  395.  
  396.    SYNOPSIS
  397.     LV_FreeListView(gadget, prev);
  398.             D0    A0
  399.  
  400.     void LV_FreeListView ( LONG gadget, struct Gadget *prev );
  401.  
  402.    FUNCTION
  403.     Frees all required memory of a listview gadget (and closes
  404.     lvExtraWindows).  If you have only 1 or 2 litsviews in your window
  405.     use this function - it is a little bit faster than LV_FreeListViews()
  406.     because it doesn't go through the hole gadget list.
  407.  
  408.    INPUTS
  409.     gadget - kind of listviews
  410.  
  411.     prev - listview gadget to free
  412.  
  413.    WARNING
  414.     Use only if the complete gadget list is removed from your window
  415.     (after closing or so).
  416.  
  417. js_tools.library/LV_FreeListViews        js_tools.library/LV_FreeListViews
  418.  
  419.    NAME
  420.     LV_FreeListViews -- frees all listviews in a gadget list
  421.  
  422.    SYNOPSIS
  423.     LV_FreeListViews(gadgetlist);
  424.              A0
  425.  
  426.     void LV_FreeListViews ( struct Gadget *gadgetlist );
  427.  
  428.    FUNCTION
  429.     Frees all listview gadgets in the list of gadgets, does not close
  430.     lvExtraWindows.  You have to use LV_FreeListView() to do this.
  431.  
  432.    INPUTS
  433.     gadgetlist - gadgets
  434.  
  435.    NOTE
  436.     use this BEFORE gadtools/FreeGadgets
  437.  
  438.    EXAMPLE
  439.     CloseWindow(mywin);
  440.     LV_FreeListView(glp);
  441.     FreeGadgets(glp);
  442.  
  443.    SEE ALSO
  444.     LV_FreeListView(),gadtools/FreeGadgets()
  445.  
  446. js_tools.library/LV_GetIMsg              js_tools.library/LV_GetIMsg
  447.  
  448.    NAME
  449.     LV_GetIMsg -- get IntuiMessage
  450.  
  451.    SYNOPSIS
  452.     intuimessage = LV_GetIMsg(msgport);
  453.     D0              A0
  454.  
  455.     struct IntuiMessage *LV_GetIMsg ( struct MsgPort *msgport );
  456.  
  457.    FUNCTION
  458.     Gets a manipulated IntuiMessage of the given message port.  If this
  459.     message is only for the listview or gadtools the result is NULL.  Use
  460.     LV_ReplyIMsg() to reply! If multiselection (marking by user) is
  461.     enabled and the user used it the Qualifier field contains
  462.     MARK_QUALIFIER_SET or MARK_QUALIFIER_CLEAR, MouseX the top and MouseY
  463.     the bottom of the selected area.
  464.  
  465.    INPUTS
  466.     msgport - Message Port of a window
  467.  
  468.    RESULT
  469.     intuimessage (D0) - IntuiMessage with IDCMP or NULL if no message to
  470.         get
  471.  
  472.    NOTE
  473.     Simply replace GT_GetIMsg() in your programs.  You needn't have any
  474.     listview in this window if you use LV_GetIMsg().
  475.  
  476.    SEE ALSO
  477.     gadtools/GT_GetIMsg()
  478.  
  479.    WARNING
  480.     You MUST reply a message you got with LV_GetIMsg() with
  481.     LV_ReplyIMSG()!
  482.  
  483. js_tools.library/LV_GetListViewAttrsA    js_tools.library/LV_GetListViewAttrsA
  484.  
  485.    NAME
  486.     LV_GetListViewAttrsA -- get listview gadget attributes
  487.  
  488.    SYNOPSIS
  489.     count = LV_GetListViewAttrsA(gad, win, req);
  490.     D0                 A0   A1   A2
  491.  
  492.     LONG LV_GetListViewAttrsA ( struct Gadget *gad, struct Window *win,
  493.         struct Requester *req );
  494.  
  495.    FUNCTION
  496.     gets listview gadget attributes.  Put in the ti_Data field a pointer
  497.     to ULONG variables in which the information will be written.
  498.  
  499.    INPUTS
  500.     gad - listview gadget to manipulate
  501.  
  502.     win - window of listview gadget
  503.  
  504.     req - requester of listview gadget (NULL)
  505.  
  506.    RESULT
  507.     count (D0) - number of information put into the variables
  508.  
  509.    NOTE
  510.     Requesters are currently not supported
  511.  
  512.    TAGS
  513.     please look in LV_CreateListViewA, LV_SetListViewAttrsA(),
  514.         lv_AskListViewAttrs() and in tagitems overview at the end.
  515.  
  516.    SEE ALSO
  517.     gadtools/GT_GetGadgetAttrsA()
  518.  
  519. js_tools.library/LV_KeyHandler               js_tools.library/LV_KeyHandler
  520.  
  521.    NAME
  522.     LV_KeyHandler -- handles keys from user for listview
  523.  
  524.    SYNOPSIS
  525.     char = LV_KeyHandler(gad, im, key, tags);
  526.     D0             A0   A1  D0   A2
  527.  
  528.     WORD LV_KeyHandler ( struct Gadget *gad, struct IntuiMessage *im,
  529.         char key, struct TagItem *tags );
  530.  
  531.    FUNCTION
  532.     Handles keys in IntuiMessages in an optimal way for a listview
  533.     gadget.  Specify in "key" the character for the listview (the
  534.     underlined one in the gadget text) in lower case (important if you
  535.     use local characters like umlauts!) or 0 if you allow cursor keys.
  536.     If you only have one listview in a window then the cursor keys are
  537.     the better choice because the user may use them more intuitiv.    The
  538.     IntuiMessage must be of IDCMP class RAWKEY, if the character isn't
  539.     used for the listview you will get the ASCII value of the key as
  540.     result (0 if no ASCII conversion if possible) or -1 if the key has
  541.     been used for the listview.  Don't use such keys again to avoid
  542.     caonfusion of the user.  Simply put item "lv_Selected" in the taglist
  543.     to get the news selected item.    It's save to call this function with
  544.     a NULL gadget pointer simply to get the ASCII code of a RAWKEY.
  545.  
  546.     Keys work this way (if key==some character):
  547.      without qualifier: down
  548.      with SHIFT      : up
  549.      with ALT      : last item
  550.      with ALT + SHIFT : first item
  551.      with CONTROL      : mark/unmark selected item (if marking allowed)
  552.       (pressed SHIFT allowed)
  553.  
  554.     If cursor key mode if selected (key==0):
  555.      cursor_down      : down
  556.      cursor_up      : up
  557.      with SHIFT      : one page up/down
  558.      with ALT      : first/last item
  559.      with CONTROL      : -nothing-
  560.      SPACE          : mark/unmark selected item (if marking allowed)
  561.  
  562.     These keys may be user selectable in later versions.  The AlwaysMark
  563.     mode is ignored if you move around by keyboard.
  564.  
  565.    INPUTS
  566.     gad - listview gadget
  567.  
  568.     im - IntuiMessage wih the key
  569.  
  570.     key - listview's key or 0 if cursor keys
  571.  
  572.     tags - tagitems given to LV_GetListViewAttrsA()
  573.  
  574.    RESULT
  575.     char (D0) - ASCII character of the press or released (!) key, 0 if no
  576.         ASCII key, negative if used for listview
  577.  
  578.    TAGS
  579.     see LV_GetListViewAttrsA()
  580.  
  581.    SEE ALSO
  582.     LV_GetListViewAttrsA()
  583.  
  584.    NOTE
  585.     Currently the only way to see if the selected item has been marked is
  586.     to use an AskTag after calling this function.
  587.  
  588.    WARNING
  589.     Result is negative if key is used for listview, this is not equal
  590.     (-1)!
  591.  
  592.    BUGS
  593.     Before library release 236 chars > 127 were returned negative.
  594.  
  595.     Before library release 233 key release was handled wrong.
  596.  
  597.     Before library release 229 tagitems were not updated because
  598.     LV_GetListViewAttrsA() was not called by LV_KeyHandler().
  599.  
  600.     Before library release 224 pragma file in C includes were wrong
  601.     (tagitems were missing).
  602.  
  603.    EXAMPLE
  604.     /*
  605.      * a short part how to use this function
  606.      */
  607.      my_MSG=LV_GetIMsg(mywin->UserPort);
  608.      if (my_MSG)
  609.      {
  610.        WORD key;
  611.        if (my_MSG->Class==IDCMP_RAWKEY)
  612.        {
  613.          struct TagItem ti[2]={
  614.                 {lv_Selected,0},
  615.                 {TAG_DONE,}};
  616.          key=LV_HandleKey(mylvgg,my_MSG,0,&ti);
  617.          if (key<0) /* see! (key<0) */
  618.          {
  619.            BOOL marked;
  620.            marked=(BOOL)
  621.          AskListViewAttrs(mylvgg,lv_IsMarkedNr,ti[0].ti_Data);
  622.            /*
  623.         * now your code to handle a new selected item
  624.         * (could be found in ti[0].ti_Data) and/or marking
  625.         * a line (marked==TRUE)
  626.         */
  627.          }
  628.          else
  629.          {
  630.            /* other code to handle pressed keys */
  631.          }
  632.        }
  633.        /* more code for other IDCMP classes */
  634.        LV_ReplyIMsg(my_MSG);
  635.      }
  636.  
  637. js_tools.library/LV_RefreshWindow        js_tools.library/LV_RefreshWindow
  638.  
  639.    NAME
  640.     LV_RefreshWindow -- Refresh Listview gadgets
  641.  
  642.    SYNOPSIS
  643.     LV_RefreshWindow(Window, Requester);
  644.              A0     A1
  645.  
  646.     void LV_RefreshWindow ( struct Window *Window, struct Requester
  647.         *Requester );
  648.  
  649.    FUNCTION
  650.     Updates Listviews (e.g.  in simple refresh windows) and calls
  651.     GT_RefreshWindow().
  652.  
  653.    INPUTS
  654.     Window - window of listviews to refresh
  655.  
  656.     Requester - requester of listviews (NULL)
  657.  
  658.    NOTE
  659.     Requesters are currently not supported - set to NULL
  660.  
  661.    SEE ALSO
  662.     gadtools/GT_RefreshWindow()
  663.  
  664. js_tools.library/LV_ReplyIMsg            js_tools.library/LV_ReplyIMsg
  665.  
  666.    NAME
  667.     LV_ReplyIMsg -- replys IntuiMessage of LV_GetIMsg()
  668.  
  669.    SYNOPSIS
  670.     LV_ReplyIMsg(msg);
  671.              A1
  672.  
  673.     void LV_ReplyIMsg ( struct IntuiMessage *msg );
  674.  
  675.    FUNCTION
  676.     Replys a message of LV_GetIMsg().  Do not use some different way!
  677.  
  678.    INPUTS
  679.     msg - IntuiMessage to reply
  680.  
  681.    NOTE
  682.     It is save to give a NULL pointer as IntuiMessage!
  683.  
  684.     Simply replace GT_ReplyIMsg() in your programs.  You needn't have any
  685.     listview in this window.
  686.  
  687.    SEE ALSO
  688.     gadtools/GT_ReplyIMsg()
  689.  
  690.    WARNING
  691.     Do not try to reply a message you didn't get with LV_GetIMsg() with
  692.     this.
  693.  
  694. js_tools.library/LV_SetListViewAttrsA    js_tools.library/LV_SetListViewAttrsA
  695.  
  696.    NAME
  697.     LV_SetListViewAttrsA -- set listview gadget attributes
  698.  
  699.    SYNOPSIS
  700.     LV_SetListViewAttrsA(gad, win, req, tags);
  701.                  A0   A1   A2   A3
  702.  
  703.     void LV_SetListViewAttrsA ( struct Gadget *gad, struct Window *win,
  704.         struct Requester *req, struct TagItem *tags );
  705.  
  706.    FUNCTION
  707.     sets listview gadgets attributes with the given tagitems and refreshs
  708.     it
  709.  
  710.    INPUTS
  711.     gad - listview gadget to manipulate
  712.  
  713.     win - window of listview gadget
  714.  
  715.     req - requester of listview gadget (NULL)
  716.  
  717.     tags - tagitems for additional infos
  718.  
  719.    NOTE
  720.     Requesters are currently not supported
  721.  
  722.    TAGS
  723.     lv_Labels (struct List*) like GTLV_Labels - Text to show in struct
  724.         List* or MinList*
  725.  
  726.     lv_Disabled (BOOL) like GA_Disabled - disables listview - scrolling
  727.         is still possible so the hook could be started!
  728.  
  729.     lv_Top (LONG) like GTLV_Top - sets first show line - the real top
  730.         line is returned in ti_Data field
  731.  
  732.     lv_Selected (LONG) like GTLV_Selected - sets selected line - the real
  733.         selected line is returned in ti_Data
  734.  
  735.     lv_NewSelected (LONG) much better select function - selected line is
  736.         automatically shown by as less as possible scrolling the
  737.         listview - the real selected line is returned in ti_Data
  738.  
  739.     lv_SetMark (LONG) mark a line (0-...)
  740.  
  741.     lv_ClearMark (LONG) unmark line (0-...) - use "ask tags" to get
  742.         current state of a line
  743.  
  744.     lv_BlockStart (LONG) mark lines in a block - upper line here
  745.  
  746.     lv_BlockStop (LONG) mark lines in a block - last line here
  747.  
  748.     lv_MarkBlock (BOOL) if TRUE block is marked, if FALSE block is
  749.         unmarked
  750.  
  751.     lv_MarkIsIn (ULONG) mark offset (to struct Node start), BYTE field
  752.         the hole list will be marked/unmarked as set in this offset -
  753.         ==1==TRUE means set mark e.g.  OFFSETOF(struct
  754.         myNode,markfield)
  755.  
  756.     lv_OnlyRead (LONG) number of lines at the end of the list that are
  757.         read only
  758.  
  759.     lv_Colour (LONG) colour of text in the listview - don't use this
  760.         other or you will confuse user
  761.  
  762.     lv_Color (LONG) other name for lv_Colour (first is british english)
  763.  
  764.     lv_NewSelectMode (LONG) set NSM mode for lv_NewSelected:
  765.         NSM_ExtraLine: one line at the listview border is always
  766.                    visible (DEFAULT)
  767.         NSM_Center   : selected is centered
  768.                    (exept at start/end of the list)
  769.         NSM_NoLine   : like good old gadtools ListView
  770.         NSM_FreeLine : like NSM_ExtraLine, but the number of visible
  771.                    lines is set by lv_NewSelectLines tag.
  772.                    If you use this tag it is possible that there
  773.                    are less lines visible this is to minimize
  774.                    scrolling and not confuse the user.
  775.  
  776.     lv_NewSelectLines (LONG) lines in NSM_FreeLines mode
  777.  
  778.     lv_SetFont (struct TextAttr*) change font of listview ATTENTION!
  779.         ta_YSize must be the same! lv_Redraw (or lv_Labels) must be
  780.         in tag list!
  781.  
  782.     lv_Redraw (BOOL) redraw text of listview it is allowed to change
  783.         ln_Name field, so use this tag to update the output
  784.  
  785.     lv_OffIsIn (ULONG) offset to lock byte (see lv_MarkIsIn) If byte is
  786.         ==1 the current node is locked and can't be selected.  The
  787.         field must exist as long as you use the list, if you change
  788.         it use lv_Redraw to update output.  Tag must be used every
  789.         time lv_Lables is used or locking will be turned of.
  790.  
  791.     lv_ElseSelected (LONG) if (New)Selected points to a locked line this
  792.         tag specifies what to do: >=0 -> select next line, <= ->
  793.         select prev line (Default: 0) usefull if you program a
  794.         keyboard interface for a listview
  795.  
  796.     lv_OffColour (LONG) colour of locked text
  797.  
  798.     lv_OffColor (LONG) other name for lv_OffColour
  799.  
  800.     lv_NewKind (LONG) change listview kind (for different mark colours)
  801.  
  802.     lv_xFrontColour (LONG) text colour of marked text if LISTVIEW2_KIND
  803.         is used
  804.  
  805.     lv_xFrontColor (LONG) other name for lv_xFrontColour
  806.  
  807.     lv_xBackColour (LONG) background colour of marked text if
  808.         LISTVIEW2_KIND is used
  809.  
  810.     lv_xBackColor (LONG) right, other name for lv_xBackColour
  811.  
  812.     lv_Hook (struct Hook*) pointer to Hook.  The Hook will get a struct
  813.         lvData in A2.  Please look in C includes for description of
  814.         struct lvData.
  815.  
  816.     lv_AlwaysMark (BOOL) the default way to mark a line is to press SHIFT
  817.         key while selecting if this tag is TRUE lines are always
  818.         marked - also if SHIFT isn't pressed - lv_MarkOn tag must be
  819.         TRUE, too!
  820.  
  821.     lv_MarkOn (BOOL) turns on mark mode, so the user can mark lines if
  822.         not turned on only the program may mark a line (so SHIFT is
  823.         ignored) - default: FALSE
  824.  
  825.     lv_HorizSelected (LONG) Horizontal position in pixel (first is 0)
  826.  
  827.     lv_HorizScroll (LONG) pixels to scroll if mouse if moved left or
  828.         right out of the listview (Default: 4).
  829.  
  830.     lv_FormatText (STRPTR) Text (+0 byte) that will be fit optimal in the
  831.         listview - replacement for lv_Labels.  Column mode will be
  832.         deactivated, this tag should be used in readonly listviews.
  833.         You can start a new paragraph with ASCII#10 (Linefeed, \n).
  834.         lvExtraWindow update text form every time it is resized.  In
  835.         lvExtraWindow the text string must be available the hole time
  836.         it is applied to the listview!! In normal listviews the text
  837.         string has to be available until LV_RefreshWindow() is called
  838.         because graphics/TextFit() needs a RastPort which is not
  839.         before this call set.  This may change.
  840.  
  841.     lv_AfterHook (struct Hook*) pointer to Hook.  The hook will get a
  842.         struct lvData in A2.  This hook will be started after a line
  843.         has been print out.  Please look in C includes for
  844.         description of struct lvData.
  845.  
  846.     lv_AskTop (WORD) returns lv_Top in ti_Data field
  847.  
  848.     lv_AskLines (WORD) number of visible lines in ti_Data
  849.  
  850.     lv_AskNumber (WORD) number of lines in current list in ti_Data
  851.  
  852.     lv_AskNode (struct Node*) Selected Node in ti_Data
  853.  
  854.     lv_IsShown (BOOL) is selected item shown ? in ti_Data
  855.  
  856.     lv_IsMarked (struct Node* -> BOOL) is (struct Node*) in ti_Data
  857.         marked ? in ti_Data Set ti_Data to the node you want to known
  858.         this, call the library and look in ti_Data for result.
  859.  
  860.     lv_IsMarkedNr (LONG -> BOOL) is line in ti_Data marked ? Like
  861.         lv_IsMarked
  862.  
  863.     lv_MarkedCount (WORD) number of marked lines in ti_Data
  864.  
  865.     lv_AskHoriz (LONG) get horizontal position of SuperLV in ti_Data -
  866.         this is the only way to get this information (exept you use
  867.         LV_GetListViewAttrsA() with lv_HorizSelected)
  868.  
  869.     lv_AskHorizMax (LONG) maximal position for lv_AskHoriz, is changed by
  870.         every lv_Lables call
  871.  
  872.    SEE ALSO
  873.     gadtools/GT_SetGadgetAttrsA()
  874.  
  875. js_tools.library/Xtra: listview tag item overview
  876.  
  877.    NAME
  878.     Xtra: listview tag item overview -- listview tag item overview
  879.  
  880.    SYNOPSIS
  881.     Xtra: listview tag item overview();
  882.  
  883.  
  884.     void Xtra: listview tag item overview (void);
  885.  
  886.    FUNCTION
  887.     All tags for the listview.  Tags may be used in [C]reate, [S]et,
  888.     [G]et, e[X]clusiv if tag lv_Redraw also has to be used, or in
  889.     [A]skListViewAttrs().  These [A]sk tags can also be used in [S]et or
  890.     [G]et and return their results in ti_Data field.  Some of them must
  891.     have a start parameter in ti_Data set!
  892.  
  893.    TAGS
  894.     lv_Labels (struct List*) [CSG] like GTLV_Labels - Text to show in
  895.         struct List* or MinList*
  896.  
  897.     lv_Disabled (BOOL) [CSG] like GA_Disabled - disables listview -
  898.         scrolling is still possible so the hook could be started!
  899.  
  900.     lv_ScrollWidth (LONG) [C..] like GTLV_ScrollWidth - width of
  901.         scroller, default: 16
  902.  
  903.     lv_ShowSelected (struct Gadget*) [C..] like GTLV_ShowSelected - 0
  904.         show selected or a pointer to a stringgadget to show it there
  905.         if you use multi columns the struct Node->ln_Name field is
  906.         still used!
  907.  
  908.     lv_ReadOnly (BOOL) [C..] like GTLV_ReadOnly - ListView is readonly
  909.  
  910.     lv_Spacing (LONG) [C..] like LAYOUTA_Spacing - additional free pixel
  911.         lines between each text line (default 0)
  912.  
  913.     lv_Top (LONG) [CSG] like GTLV_Top - sets first show line - the real
  914.         top line is returned in ti_Data field
  915.  
  916.     lv_Selected (LONG) [CSG] like GTLV_Selected - sets selected line -
  917.         the real selected line is returned in ti_Data
  918.  
  919.     lv_NewSelected (LONG) [CSG] much better select function - selected
  920.         line is automatically shown by as less as possible scrolling
  921.         the listview - the real selected line is returned in ti_Data
  922.  
  923.     lv_Obsolete1 (LONG) [...] obsolete do not use!
  924.  
  925.     lv_SetMark (LONG) [CS.] mark a line (0-...)
  926.  
  927.     lv_ClearMark (LONG) [CS.] unmark line (0-...) - use "ask tags" to get
  928.         current state of a line
  929.  
  930.     lv_BlockStart (LONG) [CS.] mark lines in a block - upper line here
  931.  
  932.     lv_BlockStop (LONG) [CS.] mark lines in a block - last line here
  933.  
  934.     lv_MarkBlock (BOOL) [CS.] if TRUE block is marked, if FALSE block is
  935.         unmarked
  936.  
  937.     lv_MarkIsIn (ULONG) [CS.] mark offset (to struct Node start), BYTE
  938.         field the hole list will be marked/unmarked as set in this
  939.         offset - ==1==TRUE means set mark e.g.    OFFSETOF(struct
  940.         myNode,markfield)
  941.  
  942.     lv_OnlyRead (LONG) [CS.] number of lines at the end of the list that
  943.         are read only
  944.  
  945.     lv_Colour (LONG) [CSG] colour of text in the listview - don't use
  946.         this other or you will confuse user
  947.  
  948.     lv_Color (LONG) [CSG] other name for lv_Colour (first is british
  949.         english)
  950.  
  951.     lv_NewSelectMode (LONG) [CSG] set NSM mode for lv_NewSelected:
  952.         NSM_ExtraLine: one line at the listview border is always
  953.                    visible (DEFAULT)
  954.         NSM_Center   : selected is centered
  955.                    (exept at start/end of the list)
  956.         NSM_NoLine   : like good old gadtools ListView
  957.         NSM_FreeLine : like NSM_ExtraLine, but the number of visible
  958.                    lines is set by lv_NewSelectLines tag.
  959.                    If you use this tag it is possible that there
  960.                    are less lines visible this is to minimize
  961.                    scrolling and not confuse the user.
  962.  
  963.     lv_NewSelectLines (LONG) [CSG] lines in NSM_FreeLines mode
  964.  
  965.     lv_SetFont (struct TextAttr*) [.X.] change font of listview
  966.         ATTENTION! ta_YSize must be the same! lv_Redraw (or
  967.         lv_Labels) must be in tag list!
  968.  
  969.     lv_Redraw (BOOL) [.S.] redraw text of listview it is allowed to
  970.         change ln_Name field, so use this tag to update the output
  971.  
  972.     lv_OffIsIn (ULONG) [CSG] offset to lock byte (see lv_MarkIsIn) If
  973.         byte is ==1 the current node is locked and can't be selected.
  974.         The field must exist as long as you use the list, if you
  975.         change it use lv_Redraw to update output.  Tag must be used
  976.         every time lv_Lables is used or locking will be turned of.
  977.  
  978.     lv_ElseSelected (LONG) [CS.] if (New)Selected points to a locked line
  979.         this tag specifies what to do: >=0 -> select next line, <= ->
  980.         select prev line (Default: 0) usefull if you program a
  981.         keyboard interface for a listview
  982.  
  983.     lv_OffColour (LONG) [CSG] colour of locked text
  984.  
  985.     lv_OffColor (LONG) [CSG] other name for lv_OffColour
  986.  
  987.     lv_NewKind (LONG) [.SG] change listview kind (for different mark
  988.         colours)
  989.  
  990.     lv_xFrontColour (LONG) [CSG] text colour of marked text if
  991.         LISTVIEW2_KIND is used
  992.  
  993.     lv_xFrontColor (LONG) [CSG] other name for lv_xFrontColour
  994.  
  995.     lv_xBackColour (LONG) [CSG] background colour of marked text if
  996.         LISTVIEW2_KIND is used
  997.  
  998.     lv_xBackColor (LONG) [CSG] right, other name for lv_xBackColour
  999.  
  1000.     lv_Hook (struct Hook*) [CX.] pointer to Hook.  The Hook will get a
  1001.         struct lvData in A2.  Please look in C includes for
  1002.         description of struct lvData.
  1003.  
  1004.     lv_Notick (BOOL) [C..] do not send IDCMP_INTUITICKS if they are
  1005.         already used by listview (Default: TRUE)
  1006.  
  1007.     lv_AlwaysMark (BOOL) [CSG] the default way to mark a line is to press
  1008.         SHIFT key while selecting if this tag is TRUE lines are
  1009.         always marked - also if SHIFT isn't pressed - lv_MarkOn tag
  1010.         must be TRUE, too!
  1011.  
  1012.     lv_MarkOn (BOOL) [CSG] turns on mark mode, so the user can mark lines
  1013.         if not turned on only the program may mark a line (so SHIFT
  1014.         is ignored) - default: FALSE
  1015.  
  1016.     lv_SuperListView (BOOL) [C..] make Super ListView (TRUE) - i.e.  it
  1017.         may scroll horizontal - default: FALSE It has some things in
  1018.         common with intuitions Super Bitmap Windows.  ATTENTION! This
  1019.         kind of listview isn't that fast - so use it only for small
  1020.         listviews.  If there is less chip ram it falls back to a
  1021.         normal listview! Currently it is impossible to use a Super
  1022.         Listview in lvExtraWindows!
  1023.  
  1024.     lv_ScrollHeight (LONG) [C..] Height of horizontal scroller (see
  1025.         lv_ScrollWidth), Default: lv_ScrollWidth-(lv_ScrollWidth/3)
  1026.  
  1027.     lv_HorizSelected (LONG) [CSG] Horizontal position in pixel (first is
  1028.         0)
  1029.  
  1030.     lv_HorizScroll (LONG) [CSG] pixels to scroll if mouse if moved left
  1031.         or right out of the listview (Default: 4).
  1032.  
  1033.     lv_Private1 (LONG) [C..] private tagitem, do not use
  1034.  
  1035.     lv_ColumnData (struct ColumnData*)[] [C..] pointer to a ColumnData
  1036.         array.    Listviews may have more than one column.  Each column
  1037.         is represented by one struct ColumnData that contains its
  1038.         width, where is starts, Text adjustment and an offset to the
  1039.         text in each Node (see lv_MarkIsIn).  Field ln_Name of the
  1040.         struct Node is not shown so you must add a ColumnData for it,
  1041.         too.  But it is shown in an added string gadget.  To end the
  1042.         array simply add a ColumnData with all fields set to 0
  1043.         (NULL).  The array has to be sorted by size of start -
  1044.         smallest first.  Please look in C includes for details of
  1045.         struct ColumnData.
  1046.  
  1047.     lv_FormatText (STRPTR) [CS.] Text (+0 byte) that will be fit optimal
  1048.         in the listview - replacement for lv_Labels.  Column mode
  1049.         will be deactivated, this tag should be used in readonly
  1050.         listviews.  You can start a new paragraph with ASCII#10
  1051.         (Linefeed, \n).  lvExtraWindow update text form every time it
  1052.         is resized.  In lvExtraWindow the text string must be
  1053.         available the hole time it is applied to the listview!! In
  1054.         normal listviews the text string has to be available until
  1055.         LV_RefreshWindow() is called because graphics/TextFit() needs
  1056.         a RastPort which is not before this call set.  This may
  1057.         change.
  1058.  
  1059.     lv_AfterHook (struct Hook*) [CX.] pointer to Hook.  The hook will get
  1060.         a struct lvData in A2.    This hook will be started after a
  1061.         line has been print out.  Please look in C includes for
  1062.         description of struct lvData.
  1063.  
  1064.     lv_AskTop (WORD) [A] returns lv_Top in ti_Data field
  1065.  
  1066.     lv_AskLines (WORD) [A] number of visible lines in ti_Data
  1067.  
  1068.     lv_AskNumber (WORD) [A] number of lines in current list
  1069.  
  1070.     lv_AskNode (struct Node*) [A] Selected Node
  1071.  
  1072.     lv_IsShown (BOOL) [A] is selected item shown ?
  1073.  
  1074.     lv_IsMarked (struct Node* -> BOOL) [A] is (struct Node*) in ti_Data
  1075.         marked ? Set ti_Data to the node you want to known this, call
  1076.         the library and look in ti_Data for result.
  1077.  
  1078.     lv_IsMarkedNr (LONG -> BOOL) [A] is line in ti_Data marked ? Like
  1079.         lv_IsMarked
  1080.  
  1081.     lv_MarkedCount (WORD) [A] number of marked lines
  1082.  
  1083.     lv_AskHoriz (LONG) [A] get horizontal position of SuperLV - this is
  1084.         the only way to get this information (exept you use
  1085.         LV_GetListViewAttrsA() with lv_HorizSelected)
  1086.  
  1087.     lv_AskHorizMax (LONG) [A] maximal position for lv_AskHoriz, is
  1088.         changed by every lv_Lables call
  1089.  
  1090.